Make `FirstNames` optional in `Persons` records in package metadata #5822

ThomasBreuer · 2024-10-22T21:46:54Z

resolves #5768

fingolfin · 2024-10-24T06:45:43Z

Just to double-check, did you verify the resulting citations look reasonable?

ThomasBreuer · 2024-10-24T13:22:42Z

@fingolfin I get the following.

gap> Cite( "alnuth" );
Please use one of the following samples
to cite Alnuth version from this installation

Text:

[ADET22]  Assmann,  B.,  Distler,  A.,  Eick,  B.  and The GAP Team, Alnuth,
ALgebraic  NUmber  THeory  and  an  interface  to  PARI/GP, Version 3.2.1dev
(2022), GAP package, https://gap-packages.github.io/alnuth.

HTML:

<p class='BibEntry'>
[<span class='BibKey'>ADET22</span>]   <b class='BibAuthor'>Assmann, B., Distl\
er, A., Eick, B. and The GAP Team</b>,
 <i class='BibTitle'>Alnuth, ALgebraic NUmber THeory and an interface to PARI/\
GP,
         Version 3.2.1dev</i>
 (<span class='BibYear'>2022</span>)<br />
(<span class='BibNote'>GAP package</span>),
<span class='BibHowpublished'><a href="https://gap-packages.github.io/alnuth">\
https://gap-packages.github.io/alnuth</a></span>.
</p>

BibXML:

<entry id="Alnuth"><misc>
  <author>
    <name><first>Björn</first><last>Assmann</last></name>
    <name><first>Andreas</first><last>Distler</last></name>
    <name><first>Bettina</first><last>Eick</last></name>
    <name><last>The GAP Team</last></name>
  </author>
  <title><C>Alnuth</C>, ALgebraic NUmber THeory and an interface to PARI/GP,
         <C>V</C>ersion 3.2.1dev</title>
  <howpublished><URL>https://gap-packages.github.io/alnuth</URL></howpublished\
>
  <month>Apr</month>
  <year>2022</year>
  <note>GAP package</note>
  <keywords>algebraic number theory; number field; maximal order; interface to\
 PARI/GP; unit group; elements of given norm</keywords>
</misc></entry>

BibTeX:

@misc{ Alnuth,
  author =           {Assmann,  B.  and Distler, A. and Eick, B. and The GAP
                      Team},
  title =            {{Alnuth},  ALgebraic NUmber THeory and an interface to
                      PARI/GP, {V}ersion 3.2.1dev},
  month =            {Apr},
  year =             {2022},
  note =             {GAP package},
  howpublished =     {\href          {https://gap-packages.github.io/alnuth}
                      {\texttt{https://gap\texttt{\symbol{45}}packages.github.\
io/}\discretionary
                      {}{}{}\texttt{alnuth}}},
  keywords =         {algebraic  number theory; number field; maximal order;
                      interface  to  PARI/GP;  unit group; elements of given
                      norm},
  printedkey =       {ADET22}
}

Compared the result shown in #5768, this looks reasonable.

frankluebeck · 2024-10-24T16:19:51Z

In my opinion this does not fix the problem in #5768.

This in not a problem with the code in GAP or GAPDoc but with the input. In the PackageInfo.g of the alnuth package we find:

Persons := [
  ...
 rec(
      LastName      := "GAP Team",
      FirstNames    := "The",
      IsAuthor      := false,
      IsMaintainer  := true,
      Email         := "support@gap-system.org",
 ),
],

and therefore it is correct that the The part is treated like a first name.

The PackageInfo.g should be changed to:

Persons := [
  ...
 rec(
      LastName      := "The GAP Team",
      IsAuthor      := false,
      IsMaintainer  := true,
      Email         := "support@gap-system.org",
 ),
],

But then there is a problem in BibEntry in file lib/package.gi which assumes that the component .FirstNames is bound. That function should probably treat .FirstNames as optional.

So, let's try:

Persons := [
  ...
 rec(
      LastName      := "The GAP Team",
      FirstNames    := "",
      IsAuthor      := false,
      IsMaintainer  := true,
      Email         := "support@gap-system.org",
 ),
],

Then we get:

Please use one of the following samples
to cite Alnuth version from this installation

Text:

[ADET22]  Assmann, B., Distler, A., Eick, B. and The GAP Team, , Alnuth, Algebraic number theory and an interface to PARI/GP, Version
3.2.1 (2022), GAP package, https://gap-packages.github.io/alnuth.

HTML:

<p class='BibEntry'>
[<span class='BibKey'>ADET22</span>]   <b class='BibAuthor'>Assmann, B., Distler, A., Eick, B. and The GAP Team,</b>,
 <i class='BibTitle'>Alnuth, Algebraic number theory and an interface to PARI/GP,
         Version 3.2.1</i>
 (<span class='BibYear'>2022</span>)<br />
(<span class='BibNote'>GAP package</span>),
<span class='BibHowpublished'><a href="https://gap-packages.github.io/alnuth">https://gap-packages.github.io/alnuth</a></span>.
</p>

BibXML:

<entry id="Alnuth"><misc>
  <author>
    <name><first>Björn</first><last>Assmann</last></name>
    <name><first>Andreas</first><last>Distler</last></name>
    <name><first>Bettina</first><last>Eick</last></name>
    <name><first></first><last>The GAP Team</last></name>
  </author>
  <title><C>Alnuth</C>, Algebraic number theory and an interface to PARI/GP,
         <C>V</C>ersion 3.2.1</title>
  <howpublished><URL>https://gap-packages.github.io/alnuth</URL></howpublished>
  <month>Apr</month>
  <year>2022</year>
  <note>GAP package</note>
  <keywords>algebraic number theory; number field; maximal order; interface to PARI/GP; unit group; elements of given norm</keywords>
</misc></entry>

BibTeX:

@misc{ Alnuth,
  author =           {Assmann, B. and Distler, A. and Eick, B. and The GAP Team,},
  title =            {{Alnuth}, Algebraic number theory and an interface to PARI/GP, {V}ersion 3.2.1},
  month =            {Apr},
  year =             {2022},
  note =             {GAP package},
  howpublished =     {\href                                                                   {https://gap-packages.github.io/alnuth}
                      {\texttt{https://gap\texttt{\symbol{45}}packages.github.io/}\discretionary {}{}{}\texttt{alnuth}}},
  keywords =         {algebraic number theory; number field; maximal order; interface to PARI/GP; unit group; elements of given norm},
  printedkey =       {ADET22}
}

This looks almost good, except that the BibTeX version should be further improved. This is done in a new commit in GAPDoc: frankluebeck/GAPDoc@b3544aa

One further comment: In BibEntry it would be better to enclose the pkginfo.Subtitle with <C> tags. Then we would get in the BibTeX version of the example above {}'s around Algebraic ... PARI/GP and this would avoid that many bib styles translate the PARI/GP to lower case.

fingolfin · 2024-10-24T21:19:33Z

With FirstNames := "" not only the BibTeX output has issues, but also the plain text and HTML versions, which include The GAP Team, , Alnuth respectively The GAP Team,</b>,

ThomasBreuer · 2024-10-25T12:33:52Z

Thanks for the comments.
Yes, the source of the problem is not "a bad guess" in interpreting unstructured data but a bad choice for structured data.
(And the latter was caused by bad validations.)

How shall we proceed?

I think it is uncontroversial that the FirstNames components in Person records in PackageInfo.g should become optional. For that, the functions BibEntry and ValidatePackageInfo must be changed, and the changes must be documented.
BibEntry can be changed such that additional <C> tags get added.
The 34 (?) packages which currently have a "The GAP Team" person in their PackageInfo.g files can be changed such that this string goes to LastName, and FirstNames is omitted. (Shall we keep the wrong output until this has happened, or should we add the currently proposed change as a workaound until then?)

- make `FirstNames` in `Person` records of `PackageInfo.g` files optional - let `BibEntry` add `<C>` tags for `Subtitle`

fingolfin · 2024-10-28T09:48:56Z

lib/package.gi

@@ -2402,7 +2404,7 @@ InstallGlobalFunction( ValidatePackageInfo, function( info )
       and IsBound( record.Persons ) then
      for subrec in record.Persons do
        TestMandat( subrec, "LastName", IsString, "a string" );
-        TestMandat( subrec, "FirstNames", IsString, "a string" );
+        TestOption( subrec, "FirstNames", IsString, "a string" );


If we make it optional here we should also adjust doc/ref/gappkg.xml to say it is (now) optional. (Indeed besides moving it from the list of required components to optional ones, I'd add some text to the effect "since GAP 4.14 this is optional" or so

fingolfin · 2024-10-28T09:55:19Z

I agree with @ThomasBreuer's assessment. So we should first get his PR merged (so that FirstNames becomes optional), ideally in time for GAP 4.14.0. Once that is out, I can let a script run to update all affected packages to use the new author format for "The GAP Team". That's a matter of maybe 10 minutes for work.

Then over time as those packages get new releases this will be fixed.

Of course would also immediately make releases just for that. Thing is, while making the actual release (creating & uploading tarballs etc.) is quick thanks to ReleaseTools, there is still manual work needed to update the version & release date in PackageInfo.g and in CHANGES files (if there is one). This is hard to automate right now as every package handles CHANGES files & versioning schemes differently. For 35 packages I think 2-3 packages per package is a low estimate, but already adds up to 1-2 hours of work. I don't think it's worth this bother.

special treatment for The GAP Team in Cite

b7afe87

ThomasBreuer added kind: bug Issues describing general bugs, and PRs fixing them topic: library release notes: not needed PRs introducing changes that are wholly irrelevant to the release notes labels Oct 22, 2024

ThomasBreuer requested a review from frankluebeck October 23, 2024 12:41

ThomasBreuer added 2 commits October 25, 2024 16:16

address some comments

51aba90

- make `FirstNames` in `Person` records of `PackageInfo.g` files optional - let `BibEntry` add `<C>` tags for `Subtitle`

adjust test output to the added <C> tags

f4655da

fingolfin reviewed Oct 28, 2024

View reviewed changes

address a comment: adjust gappkg.xml

b3f4338

fingolfin changed the title ~~special treatment for The GAP Team in Cite~~ Make FirstNames optional in Persons records in package metadata Oct 28, 2024

fingolfin approved these changes Oct 28, 2024

View reviewed changes

fingolfin added release notes: use title For PRs: the title of this PR is suitable for direct use in the release notes and removed release notes: not needed PRs introducing changes that are wholly irrelevant to the release notes labels Oct 28, 2024

fingolfin merged commit 17bc592 into gap-system:master Oct 28, 2024
31 of 33 checks passed

ThomasBreuer deleted the TB_Cite_The_GAP_Team branch October 29, 2024 08:14

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Make `FirstNames` optional in `Persons` records in package metadata #5822

Make `FirstNames` optional in `Persons` records in package metadata #5822

ThomasBreuer commented Oct 22, 2024

fingolfin commented Oct 24, 2024

ThomasBreuer commented Oct 24, 2024

frankluebeck commented Oct 24, 2024

fingolfin commented Oct 24, 2024

ThomasBreuer commented Oct 25, 2024

fingolfin Oct 28, 2024

fingolfin commented Oct 28, 2024

Make FirstNames optional in Persons records in package metadata #5822

Make FirstNames optional in Persons records in package metadata #5822

Conversation

ThomasBreuer commented Oct 22, 2024

fingolfin commented Oct 24, 2024

ThomasBreuer commented Oct 24, 2024

frankluebeck commented Oct 24, 2024

fingolfin commented Oct 24, 2024

ThomasBreuer commented Oct 25, 2024

fingolfin Oct 28, 2024

Choose a reason for hiding this comment

fingolfin commented Oct 28, 2024

Make `FirstNames` optional in `Persons` records in package metadata #5822

Make `FirstNames` optional in `Persons` records in package metadata #5822